Static Site Generation (Eleventy)
**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json) - [README.md](file://README.md) - [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk) - [src/_includes/layouts/iaa-base.njk](file://src/_includes/layouts/iaa-base.njk) - [src/_includes/macros/case-study-card.njk](file://src/_includes/macros/case-study-card.njk) - [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk) - [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk) - [src/_data/site.json](file://src/_data/site.json) - [src/_data/testimonials.json](file://src/_data/testimonials.json) - [src/_data/capabilities.json](file://src/_data/capabilities.json) - [src/index.njk](file://src/index.njk) - [src/content/news/2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md) - [src/content/cases/adelaide-city-fc.md](file://src/content/cases/adelaide-city-fc.md) - [src/admin/config.yml](file://src/admin/config.yml)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document explains how the Eleventy static site generation system builds the site from Markdown content through Nunjucks templates to final HTML output. It covers the template system (layouts, macros, and component reusability), the data collection pipeline (Markdown front matter, global data files, and CMS), filters and shortcodes for content processing, transforms for build-time optimization (including HTML minification and search index generation), and the relationship between Eleventy collections and the content management workflow. Practical examples demonstrate template inheritance, macro usage, and data binding, along with guidance for extending the template system and adding new content types.
Project Structure
The Eleventy project organizes content and templates under src/, with global data under src/_data/, reusable macros under src/_includes/macros/, and layouts under src/_includes/layouts/. The build configuration is defined in .eleventy.js, and the site’s runtime and search indexing are integrated via package.json scripts.
graph TB
A[".eleventy.js"] --> B["src/index.njk"]
A --> C["src/_includes/layouts/base.njk"]
A --> D["src/_includes/layouts/iaa-base.njk"]
A --> E["src/_includes/macros/*.njk"]
A --> F["src/_data/*.json"]
A --> G["src/content/*.md"]
A --> H["src/admin/config.yml"]
I["package.json"] --> J["Pagefind search index generation"]
K["README.md"] --> L["Eleventy reference and filters"]
Diagram sources
- [.eleventy.js](file://.eleventy.js)
- [src/index.njk](file://src/index.njk)
- [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
- [src/_includes/layouts/iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
- [src/_includes/macros/case-study-card.njk](file://src/_includes/macros/case-study-card.njk)
- [src/_data/site.json](file://src/_data/site.json)
- [src/admin/config.yml](file://src/admin/config.yml)
- [package.json](file://package.json)
- [README.md](file://README.md)
Section sources
- [README.md](file://README.md)
Core Components
- Build configuration and transforms: Defines passthrough copies, watch targets, shortcodes, filters, collections, and HTML minification for production.
- Template system: Base layouts and IAA-specific layouts provide consistent structure; macros encapsulate reusable UI components.
- Data sources: Global JSON data files are globally scoped; Markdown front matter supplies per-page data; CMS manages structured content.
- Collections: Curated groups of Markdown content enable templating loops and filtered listings.
- Search integration: Pagefind is invoked after Eleventy builds to produce a client-side search index.
Section sources
- [.eleventy.js](file://.eleventy.js)
- [README.md](file://README.md)
Architecture Overview
The build pipeline transforms Markdown and Nunjucks into HTML, applies transforms for syntax conversion and minification, and integrates search indexing. Collections power dynamic listings and paginated views.
sequenceDiagram
participant Dev as "Developer"
participant Eleventy as ".eleventy.js"
participant FS as "src/content/*.md"
participant Tpl as "Nunjucks Templates"
participant Out as "_site/"
participant Pagefind as "Pagefind"
Dev->>Eleventy : Run build script
Eleventy->>FS : Read Markdown with front matter
Eleventy->>Tpl : Render with layouts and macros
Tpl-->>Out : Write HTML files
Eleventy->>Out : Apply transforms (wikilinks, callouts, minify)
Eleventy->>Pagefind : Generate search index in _site/
Pagefind-->>Out : Index files and WASM
Out-->>Dev : Static site ready
Diagram sources
- [.eleventy.js](file://.eleventy.js)
- [package.json](file://package.json)
Detailed Component Analysis
Template System: Layouts and Macros
- Base layout: Provides global head metadata, navigation, search modal, main content area, and footer. It exposes variables like title, description, site, and page.url for SEO and navigation.
- IAA layout: A specialized layout for member-only pages with IAA branding and simplified navigation.
- Macros: Encapsulate reusable components such as cards for case studies, news articles, team members, testimonials, and CTAs. They accept parameters and render consistent markup.
classDiagram
class BaseLayout {
+head(meta, links, ld+json)
+navigation(active links)
+search_modal()
+main(content)
+footer(site data)
}
class IAALayout {
+head(meta, links)
+navigation(links)
+main(content)
+footer(iaa branding)
}
class CaseStudyCard {
+card(item)
}
class NewsArticleCard {
+card(item, variant)
}
class TeamFlipCard {
+card(item)
}
BaseLayout <.. CaseStudyCard : "used by"
BaseLayout <.. NewsArticleCard : "used by"
BaseLayout <.. TeamFlipCard : "used by"
IAALayout <.. CaseStudyCard : "used by"
IAALayout <.. NewsArticleCard : "used by"
IAALayout <.. TeamFlipCard : "used by"
Diagram sources
- [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
- [src/_includes/layouts/iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
- [src/_includes/macros/case-study-card.njk](file://src/_includes/macros/case-study-card.njk)
- [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
- [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
Section sources
- [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
- [src/_includes/layouts/iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
- [src/_includes/macros/case-study-card.njk](file://src/_includes/macros/case-study-card.njk)
- [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
- [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
Data Collection System
- Global data: Files under src/_data/ are automatically available in templates using their filenames as keys (e.g., site.json, testimonials.json, capabilities.json).
- Markdown front matter: Per-page data (title, date, author, excerpt, image, etc.) is parsed and merged into item.data for use in templates.
- CMS: Sveltia CMS defines collections and fields for editors to manage content and global settings. Changes commit to the repository and trigger rebuilds.
flowchart TD
A["Markdown files (*.md)"] --> B["Front matter parsed"]
C["Global data (_data/*.json)"] --> D["Template variables"]
B --> E["item.data"]
E --> F["Collections (news, cases, teamMembers, etc.)"]
D --> F
F --> G["Templates render lists and pages"]
H["Sveltia CMS config.yml"] --> A
H --> C
Diagram sources
- [.eleventy.js](file://.eleventy.js)
- [src/_data/site.json](file://src/_data/site.json)
- [src/_data/testimonials.json](file://src/_data/testimonials.json)
- [src/_data/capabilities.json](file://src/_data/capabilities.json)
- [src/admin/config.yml](file://src/admin/config.yml)
Section sources
- [.eleventy.js](file://.eleventy.js)
- [src/_data/site.json](file://src/_data/site.json)
- [src/_data/testimonials.json](file://src/_data/testimonials.json)
- [src/_data/capabilities.json](file://src/_data/capabilities.json)
- [src/admin/config.yml](file://src/admin/config.yml)
Filters and Shortcodes
- Shortcodes: Provide dynamic content such as current year and formatted current date.
- Filters: Offer transformations for arrays (limit, skip, sortBy, where, unique), strings (slug, truncate, split), dates (dateFormat), content (firstParagraph, readingTime), and utilities (dump, log, nl2br).
flowchart TD
Start(["Template rendering"]) --> Shortcodes["Shortcodes: year, currentDate"]
Start --> Filters["Filters: limit, skip, slug, truncate,<br/>dateFormat, sortBy, where, unique,<br/>firstParagraph, readingTime, nl2br, dump, log, split"]
Shortcodes --> Output["Rendered HTML"]
Filters --> Output
Diagram sources
- [.eleventy.js](file://.eleventy.js)
Section sources
- [.eleventy.js](file://.eleventy.js)
- [README.md](file://README.md)
Collections and Content Management Workflow
- Collections: Curated groups of Markdown content enable templating loops and filtered listings. Examples include news, cases, teamMembers, newsletters, services, and knowledge.
- CMS workflow: Editors manage content via Sveltia CMS; changes commit to the repository and trigger automatic rebuilds.
sequenceDiagram
participant Editor as "Editor"
participant CMS as "Sveltia CMS"
participant Repo as "Git Repository"
participant Build as "Eleventy Build"
participant Site as "Published Site"
Editor->>CMS : Edit content (front matter, markdown)
CMS->>Repo : Commit changes
Repo->>Build : Trigger build
Build->>Build : Parse front matter, apply filters, render templates
Build-->>Site : Publish _site/
Site-->>Editor : View updated content
Diagram sources
- [src/admin/config.yml](file://src/admin/config.yml)
- [.eleventy.js](file://.eleventy.js)
Section sources
- [.eleventy.js](file://.eleventy.js)
- [README.md](file://README.md)
Build Optimization and Search Index
- Transforms:
- obsidianSyntax: Converts Obsidian wikilinks and callouts to styled HTML.
- htmlmin: Minifies HTML in production builds.
- Search: Pagefind is invoked post-build to generate a client-side search index inside _site/.
flowchart TD
A["_site/*.html"] --> B["obsidianSyntax transform"]
B --> C["htmlmin transform (production)"]
C --> D["Pagefind index generation"]
D --> E["_site/pagefind/"]
Diagram sources
- [.eleventy.js](file://.eleventy.js)
- [package.json](file://package.json)
Section sources
- [.eleventy.js](file://.eleventy.js)
- [package.json](file://package.json)
Practical Examples
Template Inheritance and Data Binding
- Example: The homepage inherits from the base layout and binds global data (site metadata) and collections (news, teamMembers, testimonials, capabilities).
- Example: A news article uses front matter for title, date, and excerpt, then renders content via a macro for article cards.
sequenceDiagram
participant T as "src/index.njk"
participant L as "base.njk"
participant D as "_data/*.json"
participant C as "collections.*"
participant M as "macros/*.njk"
T->>L : layout : base.njk
T->>D : site.*, testimonials.*, capabilities.*
T->>C : collections.news, collections.teamMembers
T->>M : import and call macros
L-->>T : renders with global head/footer
Diagram sources
- [src/index.njk](file://src/index.njk)
- [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
- [src/_data/site.json](file://src/_data/site.json)
- [src/_data/testimonials.json](file://src/_data/testimonials.json)
- [src/_data/capabilities.json](file://src/_data/capabilities.json)
- [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
- [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
Section sources
- [src/index.njk](file://src/index.njk)
- [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
- [src/_data/site.json](file://src/_data/site.json)
- [src/_data/testimonials.json](file://src/_data/testimonials.json)
- [src/_data/capabilities.json](file://src/_data/capabilities.json)
- [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
- [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
Macro Usage
- Case study card macro accepts an item and renders media, category, client, title, content, and optional quote.
- News article card macro supports multiple variants (e.g., carousel vs. expanded) and uses filters for date formatting and content truncation.
- Team flip card macro renders a flip card with front/back content bound to item.data.
Section sources
- [src/_includes/macros/case-study-card.njk](file://src/_includes/macros/case-study-card.njk)
- [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
- [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
Data Binding from Front Matter
- News article front matter includes title, date, author, excerpt, image, pdf_url, pdf_label, and featured flag.
- Case study front matter includes client, category, title, image, quote, quote_author, order, and featured.
Section sources
- [src/content/news/2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md)
- [src/content/cases/adelaide-city-fc.md](file://src/content/cases/adelaide-city-fc.md)
Dependency Analysis
Eleventy orchestrates the build, while external tools handle search and deployment. The configuration defines passthrough copies for assets and admin, watch targets for efficient development, and transforms for production.
graph TB
Eleventy[".eleventy.js"] --> Passthrough["addPassthroughCopy"]
Eleventy --> Watch["addWatchTarget"]
Eleventy --> Shortcodes["addShortcode"]
Eleventy --> Filters["addFilter"]
Eleventy --> Collections["addCollection"]
Eleventy --> Transforms["obsidianSyntax, htmlmin"]
Package["package.json"] --> Pagefind["pagefind"]
Package --> Build["eleventy"]
Build --> Site["_site/"]
Pagefind --> Site
Diagram sources
- [.eleventy.js](file://.eleventy.js)
- [package.json](file://package.json)
Section sources
- [.eleventy.js](file://.eleventy.js)
- [package.json](file://package.json)
Performance Considerations
- HTML minification: Enabled in production to reduce payload sizes.
- Asset passthrough: Static assets are copied directly to avoid processing overhead.
- Transform ordering: Obsidian syntax conversion occurs before minification to ensure minification operates on final HTML.
- Watch targets: CSS, JS, and data folders are watched to speed up development rebuilds.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
- Missing macros or layouts: Verify import paths and layout references in templates.
- Incorrect data scoping: Confirm global data keys match template variable names and that front matter keys align with template usage.
- Build failures: Check transform conditions (e.g., HTML-only transforms) and environment variables for production minification.
- Search not working: Ensure Pagefind runs after Eleventy completes and that _site/pagefind/ exists.
Section sources
- [.eleventy.js](file://.eleventy.js)
- [package.json](file://package.json)
Conclusion
The Eleventy site leverages a modular template system with base and specialized layouts, reusable macros, curated collections, and a robust data pipeline combining Markdown front matter, global JSON data, and CMS-managed content. Build-time transforms optimize output, and Pagefind enables fast client-side search. The documented patterns and examples provide a clear foundation for extending templates and adding new content types.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
Extending the Template System
- Add a new layout: Place a new layout under src/_includes/layouts/ and reference it in templates via the front matter layout key.
- Create a macro: Add a new macro under src/_includes/macros/ and import it in templates to reuse UI components.
- Introduce a new collection: Define a new addCollection function in .eleventy.js to group Markdown content by glob pattern and sorting criteria.
- Add a shortcode or filter: Extend .eleventy.js with addShortcode or addFilter to provide reusable helpers and transformations.
Section sources
- [.eleventy.js](file://.eleventy.js)
- [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
- [src/_includes/macros/case-study-card.njk](file://src/_includes/macros/case-study-card.njk)
Adding New Content Types
- Define a new Markdown collection: Create a new directory under src/content/ and add a matching addCollection in .eleventy.js.
- Configure CMS fields: Extend src/admin/config.yml with a new collection and fields to support editor workflows.
- Bind data in templates: Use item.data and collections to render new content types consistently across pages.
Section sources
- [src/admin/config.yml](file://src/admin/config.yml)
- [.eleventy.js](file://.eleventy.js)